<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en"><head>

	
		<meta http-equiv="Content-type" content="text/html; charset=UTF-8">
		<meta http-equiv="Content-Language" content="en-us">

		<title>Django | Internationalization | Django Documentation</title>

		<meta name="ROBOTS" content="ALL">
		<meta http-equiv="imagetoolbar" content="no">
		<meta name="MSSmartTagsPreventParsing" content="true">
		<meta name="Copyright" content="This site's design and contents Copyright (c) 2005  Lawrence Journal-World.">

		<meta name="keywords" content="Python, Django, framework, open-source">
		<meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.">

		<link href="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/base.css" rel="stylesheet" type="text/css" media="screen">
		<link href="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/print.css" rel="stylesheet" type="text/css" media="print">
      
  
  <style type="text/css" media="screen">
    #docs-search {
      color: #000;
      float: right;
    }
    #docs-search form {
      font-size: 92%;
      margin: 0;
      padding: 1em 1em 0;
      white-space: nowrap;
    }
    form.search ul {
      list-style: none;
      margin: 0;
      padding: 0;
    }
    form.search li {
      display: inline;
      padding-right: 1em;
    }
    form.search .query {
      width: 18em;
    }
  </style>
  <link rel="stylesheet" href="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/pygments.css" type="text/css">

	</head><body id="documentation" class="default">

	<div id="container">
		<div id="header">
			<h1 id="logo"><a href="http://www.djangoproject.com/"><img src="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/hdr_logo.gif" alt="Django"></a></h1>
			<ul id="nav-global">
				<li id="nav-homepage"><a href="http://www.djangoproject.com/">Home</a></li>
				<li id="nav-download"><a href="http://www.djangoproject.com/download/">Download</a></li>
				<li id="nav-documentation"><a href="http://docs.djangoproject.com/">Documentation</a></li>
				<li id="nav-weblog"><a href="http://www.djangoproject.com/weblog/">Weblog</a></li>
				<li id="nav-community"><a href="http://www.djangoproject.com/community/">Community</a></li>
				<li id="nav-code"><a href="http://code.djangoproject.com/">Code</a></li>
			</ul>
		</div>
		<!-- END Header -->
		<div id="billboard">
  <h2><a href="http://docs.djangoproject.com/en/1.0/">Django documentation</a></h2>
</div>
		<div id="columnwrap">
			
		<div id="content-main">
		


  <h2 class="deck">
  
    This document describes Django version 1.0. For development documentation, 
    <a href="http://docs.djangoproject.com/en/dev/topics/i18n/">go here</a>.
  
  </h2>
  <div class="section" id="s-internationalization">
<span id="s-topics-i18n"></span><span id="internationalization"></span><span id="topics-i18n"></span><h1>Internationalization<a class="headerlink" href="#internationalization" title="Permalink to this headline">¶</a></h1>
<p>Django has full support for internationalization of text in code and templates.
Here’s how it works.</p>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>The goal of internationalization is to allow a single Web application to offer
its content and functionality in multiple languages.</p>
<p>You, the Django developer, can accomplish this goal by adding a minimal amount
of hooks to your Python code and templates. These hooks are called
<strong>translation strings</strong>. They tell Django: “This text should be translated into
the end user’s language, if a translation for this text is available in that
language.”</p>
<p>Django takes care of using these hooks to translate Web apps, on the fly,
according to users’ language preferences.</p>
<p>Essentially, Django does two things:</p>
<ul class="simple">
<li>It lets developers and template authors specify which parts of their apps
should be translatable.</li>
<li>It uses these hooks to translate Web apps for particular users according
to their language preferences.</li>
</ul>
</div>
<div class="section" id="s-if-you-don-t-need-internationalization-in-your-app">
<span id="if-you-don-t-need-internationalization-in-your-app"></span><h2>If you don’t need internationalization in your app<a class="headerlink" href="#if-you-don-t-need-internationalization-in-your-app" title="Permalink to this headline">¶</a></h2>
<p>Django’s internationalization hooks are on by default, and that means there’s a
bit of i18n-related overhead in certain places of the framework. If you don’t
use internationalization, you should take the two seconds to set
<a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/settings/#setting-USE_I18N"><tt class="xref docutils literal"><span class="pre">USE_I18N</span> <span class="pre">=</span> <span class="pre">False</span></tt></a> in your settings file. If
<a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/settings/#setting-USE_I18N"><tt class="xref docutils literal"><span class="pre">USE_I18N</span></tt></a> is set to <tt class="xref docutils literal"><span class="pre">False</span></tt>, then Django will make some
optimizations so as not to load the internationalization machinery.</p>
<p>You’ll probably also want to remove <tt class="docutils literal"><span class="pre">'django.core.context_processors.i18n'</span></tt>
from your <tt class="docutils literal"><span class="pre">TEMPLATE_CONTEXT_PROCESSORS</span></tt> setting.</p>
</div>
<div class="section" id="s-if-you-do-need-internationalization-three-steps">
<span id="if-you-do-need-internationalization-three-steps"></span><h2>If you do need internationalization: three steps<a class="headerlink" href="#if-you-do-need-internationalization-three-steps" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li>Embed translation strings in your Python code and templates.</li>
<li>Get translations for those strings, in whichever languages you want to
support.</li>
<li>Activate the locale middleware in your Django settings.</li>
</ol>
<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">Behind the scenes</p>
<p class="last">Django’s translation machinery uses the standard <tt class="docutils literal"><span class="pre">gettext</span></tt> module that
comes with Python.</p>
</div>
</div>
<div class="section" id="s-how-to-specify-translation-strings">
<span id="how-to-specify-translation-strings"></span><h2>1. How to specify translation strings<a class="headerlink" href="#how-to-specify-translation-strings" title="Permalink to this headline">¶</a></h2>
<p>Translation strings specify “This text should be translated.” These strings can
appear in your Python code and templates. It’s your responsibility to mark
translatable strings; the system can only translate strings it knows about.</p>
<div class="section" id="s-in-python-code">
<span id="in-python-code"></span><h3>In Python code<a class="headerlink" href="#in-python-code" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-standard-translation">
<span id="standard-translation"></span><h4>Standard translation<a class="headerlink" href="#standard-translation" title="Permalink to this headline">¶</a></h4>
<p>Specify a translation string by using the function <tt class="docutils literal"><span class="pre">ugettext()</span></tt>. It’s
convention to import this as a shorter alias, <tt class="docutils literal"><span class="pre">_</span></tt>, to save typing.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Python’s standard library <tt class="docutils literal"><span class="pre">gettext</span></tt> module installs <tt class="docutils literal"><span class="pre">_()</span></tt> into the
global namespace, as an alias for <tt class="docutils literal"><span class="pre">gettext()</span></tt>. In Django, we have chosen
not to follow this practice, for a couple of reasons:</p>
<ol class="last arabic simple">
<li>For international character set (Unicode) support, <tt class="docutils literal"><span class="pre">ugettext()</span></tt> is
more useful than <tt class="docutils literal"><span class="pre">gettext()</span></tt>. Sometimes, you should be using
<tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> as the default translation method for a particular
file. Without <tt class="docutils literal"><span class="pre">_()</span></tt> in the global namespace, the developer has to
think about which is the most appropriate translation function.</li>
<li>The underscore character (<tt class="docutils literal"><span class="pre">_</span></tt>) is used to represent “the previous
result” in Python’s interactive shell and doctest tests. Installing a
global <tt class="docutils literal"><span class="pre">_()</span></tt> function causes interference. Explicitly importing
<tt class="docutils literal"><span class="pre">ugettext()</span></tt> as <tt class="docutils literal"><span class="pre">_()</span></tt> avoids this problem.</li>
</ol>
</div>
<p>In this example, the text <tt class="docutils literal"><span class="pre">"Welcome</span> <span class="pre">to</span> <span class="pre">my</span> <span class="pre">site."</span></tt> is marked as a translation
string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ugettext</span> <span class="k">as</span> <span class="n">_</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">"Welcome to my site."</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
</pre></div>
</div>
<p>Obviously, you could code this without using the alias. This example is
identical to the previous one:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ugettext</span>

<span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">ugettext</span><span class="p">(</span><span class="s">"Welcome to my site."</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
</pre></div>
</div>
<p>Translation works on computed values. This example is identical to the previous
two:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">words</span> <span class="o">=</span> <span class="p">[</span><span class="s">'Welcome'</span><span class="p">,</span> <span class="s">'to'</span><span class="p">,</span> <span class="s">'my'</span><span class="p">,</span> <span class="s">'site.'</span><span class="p">]</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">' '</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">words</span><span class="p">))</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
</pre></div>
</div>
<p>Translation works on variables. Again, here's an identical example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">sentence</span> <span class="o">=</span> <span class="s">'Welcome to my site.'</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="n">sentence</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
</pre></div>
</div>
<p>(The caveat with using variables or computed values, as in the previous two
examples, is that Django's translation-string-detecting utility,
<tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt>, won't be able to find these strings. More on
<tt class="docutils literal"><span class="pre">makemessages</span></tt> later.)</p>
<p>The strings you pass to <tt class="docutils literal"><span class="pre">_()</span></tt> or <tt class="docutils literal"><span class="pre">ugettext()</span></tt> can take placeholders,
specified with Python's standard named-string interpolation syntax. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">my_view</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">d</span><span class="p">):</span>
    <span class="n">output</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">'Today is </span><span class="si">%(month)s</span><span class="s">, </span><span class="si">%(day)s</span><span class="s">.'</span><span class="p">)</span> <span class="o">%</span> <span class="p">{</span><span class="s">'month'</span><span class="p">:</span> <span class="n">m</span><span class="p">,</span> <span class="s">'day'</span><span class="p">:</span> <span class="n">d</span><span class="p">}</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
</pre></div>
</div>
<p>This technique lets language-specific translations reorder the placeholder
text. For example, an English translation may be <tt class="docutils literal"><span class="pre">"Today</span> <span class="pre">is</span> <span class="pre">November,</span> <span class="pre">26."</span></tt>,
while a Spanish translation may be <tt class="docutils literal"><span class="pre">"Hoy</span> <span class="pre">es</span> <span class="pre">26</span> <span class="pre">de</span> <span class="pre">Noviembre."</span></tt> -- with the
placeholders (the month and the day) with their positions swapped.</p>
<p>For this reason, you should use named-string interpolation (e.g., <tt class="docutils literal"><span class="pre">%(day)s</span></tt>)
instead of positional interpolation (e.g., <tt class="docutils literal"><span class="pre">%s</span></tt> or <tt class="docutils literal"><span class="pre">%d</span></tt>) whenever you
have more than a single parameter. If you used positional interpolation,
translations wouldn't be able to reorder placeholder text.</p>
</div>
<div class="section" id="s-marking-strings-as-no-op">
<span id="marking-strings-as-no-op"></span><h4>Marking strings as no-op<a class="headerlink" href="#marking-strings-as-no-op" title="Permalink to this headline">¶</a></h4>
<p>Use the function <tt class="docutils literal"><span class="pre">django.utils.translation.ugettext_noop()</span></tt> to mark a string
as a translation string without translating it. The string is later translated
from a variable.</p>
<p>Use this if you have constant strings that should be stored in the source
language because they are exchanged over systems or users -- such as strings in
a database -- but should be translated at the last possible point in time, such
as when the string is presented to the user.</p>
</div>
<div class="section" id="s-lazy-translation">
<span id="s-lazy-translations"></span><span id="lazy-translation"></span><span id="lazy-translations"></span><h4>Lazy translation<a class="headerlink" href="#lazy-translation" title="Permalink to this headline">¶</a></h4>
<p>Use the function <tt class="docutils literal"><span class="pre">django.utils.translation.ugettext_lazy()</span></tt> to translate
strings lazily -- when the value is accessed rather than when the
<tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> function is called.</p>
<p>For example, to translate a model's <tt class="docutils literal"><span class="pre">help_text</span></tt>, do the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ugettext_lazy</span>

<span class="k">class</span> <span class="nc">MyThing</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">help_text</span><span class="o">=</span><span class="n">ugettext_lazy</span><span class="p">(</span><span class="s">'This is the help text'</span><span class="p">))</span>
</pre></div>
</div>
<p>In this example, <tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> stores a lazy reference to the string --
not the actual translation. The translation itself will be done when the string
is used in a string context, such as template rendering on the Django admin
site.</p>
<p>The result of a <tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> call can be used wherever you would use a
unicode string (an object with type <tt class="docutils literal"><span class="pre">unicode</span></tt>) in Python. If you try to use
it where a bytestring (a <tt class="docutils literal"><span class="pre">str</span></tt> object) is expected, things will not work as
expected, since a <tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> object doesn't know how to convert
itself to a bytestring.  You can't use a unicode string inside a bytestring,
either, so this is consistent with normal Python behavior. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># This is fine: putting a unicode proxy into a unicode string.</span>
<span class="s">u"Hello </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">ugettext_lazy</span><span class="p">(</span><span class="s">"people"</span><span class="p">)</span>

<span class="c"># This will not work, since you cannot insert a unicode object</span>
<span class="c"># into a bytestring (nor can you insert our unicode proxy there)</span>
<span class="s">"Hello </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">ugettext_lazy</span><span class="p">(</span><span class="s">"people"</span><span class="p">)</span>
</pre></div>
</div>
<p>If you ever see output that looks like <tt class="docutils literal"><span class="pre">"hello</span>
<span class="pre">&lt;django.utils.functional...&gt;"</span></tt>, you have tried to insert the result of
<tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> into a bytestring. That's a bug in your code.</p>
<p>If you don't like the verbose name <tt class="docutils literal"><span class="pre">ugettext_lazy</span></tt>, you can just alias it as
<tt class="docutils literal"><span class="pre">_</span></tt> (underscore), like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ugettext_lazy</span> <span class="k">as</span> <span class="n">_</span>

<span class="k">class</span> <span class="nc">MyThing</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">help_text</span><span class="o">=</span><span class="n">_</span><span class="p">(</span><span class="s">'This is the help text'</span><span class="p">))</span>
</pre></div>
</div>
<p>Always use lazy translations in <a class="reference external" href="http://docs.djangoproject.com/en/1.0/topics/db/models/#topics-db-models"><em>Django models</em></a>.
Field names and table names should be marked for translation (otherwise, they
won't be translated in the admin interface). This means writing explicit
<tt class="docutils literal"><span class="pre">verbose_name</span></tt> and <tt class="docutils literal"><span class="pre">verbose_name_plural</span></tt> options in the <tt class="docutils literal"><span class="pre">Meta</span></tt> class,
though, rather than relying on Django's default determination of
<tt class="docutils literal"><span class="pre">verbose_name</span></tt> and <tt class="docutils literal"><span class="pre">verbose_name_plural</span></tt> by looking at the model's class
name:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ugettext_lazy</span> <span class="k">as</span> <span class="n">_</span>

<span class="k">class</span> <span class="nc">MyThing</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">_</span><span class="p">(</span><span class="s">'name'</span><span class="p">),</span> <span class="n">help_text</span><span class="o">=</span><span class="n">_</span><span class="p">(</span><span class="s">'This is the help text'</span><span class="p">))</span>
    <span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
        <span class="n">verbose_name</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">'my thing'</span><span class="p">)</span>
        <span class="n">verbose_name_plural</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s">'mythings'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="s-pluralization">
<span id="pluralization"></span><h4>Pluralization<a class="headerlink" href="#pluralization" title="Permalink to this headline">¶</a></h4>
<p>Use the function <tt class="docutils literal"><span class="pre">django.utils.translation.ungettext()</span></tt> to specify pluralized
messages. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">ungettext</span>
<span class="k">def</span> <span class="nf">hello_world</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">count</span><span class="p">):</span>
    <span class="n">page</span> <span class="o">=</span> <span class="n">ungettext</span><span class="p">(</span><span class="s">'there is </span><span class="si">%(count)d</span><span class="s"> object'</span><span class="p">,</span> <span class="s">'there are </span><span class="si">%(count)d</span><span class="s"> objects'</span><span class="p">,</span> <span class="n">count</span><span class="p">)</span> <span class="o">%</span> <span class="p">{</span>
        <span class="s">'count'</span><span class="p">:</span> <span class="n">count</span><span class="p">,</span>
    <span class="p">}</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">page</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">ungettext</span></tt> takes three arguments: the singular translation string, the plural
translation string and the number of objects (which is passed to the
translation languages as the <tt class="docutils literal"><span class="pre">count</span></tt> variable).</p>
</div>
</div>
<div class="section" id="s-in-template-code">
<span id="in-template-code"></span><h3>In template code<a class="headerlink" href="#in-template-code" title="Permalink to this headline">¶</a></h3>
<p>Translations in <a class="reference external" href="http://docs.djangoproject.com/en/1.0/topics/templates/#topics-templates"><em>Django templates</em></a> uses two template
tags and a slightly different syntax than in Python code. To give your template
access to these tags, put <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">i18n</span> <span class="pre">%}</span></tt> toward the top of your template.</p>
<p>The <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">trans</span> <span class="pre">%}</span></tt> template tag translates either a constant string
(enclosed in single or double quotes) or variable content:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt">&lt;title&gt;</span><span class="cp">{%</span> <span class="k">trans</span> <span class="s2">"This is the title."</span> <span class="cp">%}</span><span class="nt">&lt;/title&gt;</span>
<span class="nt">&lt;title&gt;</span><span class="cp">{%</span> <span class="k">trans</span> <span class="nv">myvar</span> <span class="cp">%}</span><span class="nt">&lt;/title&gt;</span>
</pre></div>
</div>
<p>If the <tt class="docutils literal"><span class="pre">noop</span></tt> option is present, variable lookup still takes place, but the
original text will be returned unchanged. This is useful when "stubbing out"
content that will require translation in the future:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt">&lt;title&gt;</span><span class="cp">{%</span> <span class="k">trans</span> <span class="s2">"myvar"</span> <span class="nv">noop</span> <span class="cp">%}</span><span class="nt">&lt;/title&gt;</span>
</pre></div>
</div>
<p>It's not possible to mix a template variable inside a string within <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">trans</span>
<span class="pre">%}</span></tt>. If your translations require strings with variables (placeholders), use
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">blocktrans</span> <span class="pre">%}</span></tt>:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">blocktrans</span> <span class="cp">%}</span>This string will have <span class="cp">{{</span> <span class="nv">value</span> <span class="cp">}}</span> inside.<span class="cp">{%</span> <span class="k">endblocktrans</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>To translate a template expression -- say, using template filters -- you need
to bind the expression to a local variable for use within the translation
block:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">blocktrans</span> <span class="k">with</span> <span class="nv">value</span><span class="o">|</span><span class="nf">filter</span> <span class="k">as</span> <span class="nv">myvar</span> <span class="cp">%}</span>
This will have <span class="cp">{{</span> <span class="nv">myvar</span> <span class="cp">}}</span> inside.
<span class="cp">{%</span> <span class="k">endblocktrans</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>If you need to bind more than one expression inside a <tt class="docutils literal"><span class="pre">blocktrans</span></tt> tag,
separate the pieces with <tt class="docutils literal"><span class="pre">and</span></tt>:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">blocktrans</span> <span class="k">with</span> <span class="nv">book</span><span class="o">|</span><span class="nf">title</span> <span class="k">as</span> <span class="nv">book_t</span> <span class="k">and</span> <span class="nv">author</span><span class="o">|</span><span class="nf">title</span> <span class="k">as</span> <span class="nv">author_t</span> <span class="cp">%}</span>
This is <span class="cp">{{</span> <span class="nv">book_t</span> <span class="cp">}}</span> by <span class="cp">{{</span> <span class="nv">author_t</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endblocktrans</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>To pluralize, specify both the singular and plural forms with the
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">plural</span> <span class="pre">%}</span></tt> tag, which appears within <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">blocktrans</span> <span class="pre">%}</span></tt> and
<tt class="docutils literal"><span class="pre">{%</span> <span class="pre">endblocktrans</span> <span class="pre">%}</span></tt>. Example:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">blocktrans</span> <span class="nv">count</span> <span class="nv">list</span><span class="o">|</span><span class="nf">length</span> <span class="k">as</span> <span class="nv">counter</span> <span class="cp">%}</span>
There is only one <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span> object.
<span class="cp">{%</span> <span class="k">plural</span> <span class="cp">%}</span>
There are <span class="cp">{{</span> <span class="nv">counter</span> <span class="cp">}}</span> <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span> objects.
<span class="cp">{%</span> <span class="k">endblocktrans</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Internally, all block and inline translations use the appropriate
<tt class="docutils literal"><span class="pre">ugettext</span></tt> / <tt class="docutils literal"><span class="pre">ungettext</span></tt> call.</p>
<p>Each <tt class="docutils literal"><span class="pre">RequestContext</span></tt> has access to three translation-specific variables:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">LANGUAGES</span></tt> is a list of tuples in which the first element is the
language code and the second is the language name (translated into the
currently active locale).</li>
<li><tt class="docutils literal"><span class="pre">LANGUAGE_CODE</span></tt> is the current user's preferred language, as a string.
Example: <tt class="docutils literal"><span class="pre">en-us</span></tt>. (See <a class="reference internal" href="#how-django-discovers-language-preference"><em>3. How Django discovers language preference</em></a>,
below.)</li>
<li><tt class="docutils literal"><span class="pre">LANGUAGE_BIDI</span></tt> is the current locale's direction. If True, it's a
right-to-left language, e.g.: Hebrew, Arabic. If False it's a
left-to-right language, e.g.: English, French, German etc.</li>
</ul>
<p>If you don't use the <tt class="docutils literal"><span class="pre">RequestContext</span></tt> extension, you can get those values with
three tags:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">get_current_language</span> <span class="k">as</span> <span class="nv">LANGUAGE_CODE</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">get_available_languages</span> <span class="k">as</span> <span class="nv">LANGUAGES</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">get_current_language_bidi</span> <span class="k">as</span> <span class="nv">LANGUAGE_BIDI</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>These tags also require a <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">i18n</span> <span class="pre">%}</span></tt>.</p>
<p>Translation hooks are also available within any template block tag that accepts
constant strings. In those cases, just use <tt class="docutils literal"><span class="pre">_()</span></tt> syntax to specify a
translation string:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">some_special_tag</span> <span class="kp">_</span><span class="o">(</span><span class="s2">"Page not found"</span><span class="o">)</span> <span class="nv">value</span><span class="o">|</span><span class="nf">yesno</span><span class="o">:</span><span class="kp">_</span><span class="o">(</span><span class="s2">"yes,no"</span><span class="o">)</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>In this case, both the tag and the filter will see the already-translated
string, so they don't need to be aware of translations.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In this example, the translation infrastructure will be passed the string
<tt class="docutils literal"><span class="pre">"yes,no"</span></tt>, not the individual strings <tt class="docutils literal"><span class="pre">"yes"</span></tt> and <tt class="docutils literal"><span class="pre">"no"</span></tt>. The
translated string will need to contain the comma so that the filter
parsing code knows how to split up the arguments. For example, a German
translator might translate the string <tt class="docutils literal"><span class="pre">"yes,no"</span></tt> as <tt class="docutils literal"><span class="pre">"ja,nein"</span></tt>
(keeping the comma intact).</p>
</div>
</div>
<div class="section" id="s-working-with-lazy-translation-objects">
<span id="working-with-lazy-translation-objects"></span><h3>Working with lazy translation objects<a class="headerlink" href="#working-with-lazy-translation-objects" title="Permalink to this headline">¶</a></h3>
<p>Using <tt class="docutils literal"><span class="pre">ugettext_lazy()</span></tt> and <tt class="docutils literal"><span class="pre">ungettext_lazy()</span></tt> to mark strings in models
and utility functions is a common operation. When you're working with these
objects elsewhere in your code, you should ensure that you don't accidentally
convert them to strings, because they should be converted as late as possible
(so that the correct locale is in effect). This necessitates the use of a
couple of helper functions.</p>
<div class="section" id="s-joining-strings-string-concat">
<span id="joining-strings-string-concat"></span><h4>Joining strings: string_concat()<a class="headerlink" href="#joining-strings-string-concat" title="Permalink to this headline">¶</a></h4>
<p>Standard Python string joins (<tt class="docutils literal"><span class="pre">''.join([...])</span></tt>) will not work on lists
containing lazy translation objects. Instead, you can use
<tt class="docutils literal"><span class="pre">django.utils.translation.string_concat()</span></tt>, which creates a lazy object that
concatenates its contents <em>and</em> converts them to strings only when the result
is included in a string. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.translation</span> <span class="k">import</span> <span class="n">string_concat</span>
<span class="o">...</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">ugettext_lazy</span><span class="p">(</span><span class="s">u'John Lennon'</span><span class="p">)</span>
<span class="n">instrument</span> <span class="o">=</span> <span class="n">ugettext_lazy</span><span class="p">(</span><span class="s">u'guitar'</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">string_concat</span><span class="p">([</span><span class="n">name</span><span class="p">,</span> <span class="s">': '</span><span class="p">,</span> <span class="n">instrument</span><span class="p">])</span>
</pre></div>
</div>
<p>In this case, the lazy translations in <tt class="docutils literal"><span class="pre">result</span></tt> will only be converted to
strings when <tt class="docutils literal"><span class="pre">result</span></tt> itself is used in a string (usually at template
rendering time).</p>
</div>
<div class="section" id="s-the-allow-lazy-decorator">
<span id="the-allow-lazy-decorator"></span><h4>The allow_lazy() decorator<a class="headerlink" href="#the-allow-lazy-decorator" title="Permalink to this headline">¶</a></h4>
<p>Django offers many utility functions (particularly in <tt class="docutils literal"><span class="pre">django.utils</span></tt>) that
take a string as their first argument and do something to that string. These
functions are used by template filters as well as directly in other code.</p>
<p>If you write your own similar functions and deal with translations, you'll
face the problem of what to do when the first argument is a lazy translation
object. You don't want to convert it to a string immediately, because you might
be using this function outside of a view (and hence the current thread's locale
setting will not be correct).</p>
<p>For cases like this, use the <tt class="docutils literal"><span class="pre">django.utils.functional.allow_lazy()</span></tt>
decorator. It modifies the function so that <em>if</em> it's called with a lazy
translation as the first argument, the function evaluation is delayed until it
needs to be converted to a string.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">from</span> <span class="nn">django.utils.functional</span> <span class="k">import</span> <span class="n">allow_lazy</span>

<span class="k">def</span> <span class="nf">fancy_utility_function</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="o">...</span><span class="p">):</span>
    <span class="c"># Do some conversion on string 's'</span>
    <span class="o">...</span>
<span class="n">fancy_utility_function</span> <span class="o">=</span> <span class="n">allow_lazy</span><span class="p">(</span><span class="n">fancy_utility_function</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">allow_lazy()</span></tt> decorator takes, in addition to the function to decorate,
a number of extra arguments (<tt class="docutils literal"><span class="pre">*args</span></tt>) specifying the type(s) that the
original function can return. Usually, it's enough to include <tt class="docutils literal"><span class="pre">unicode</span></tt> here
and ensure that your function returns only Unicode strings.</p>
<p>Using this decorator means you can write your function and assume that the
input is a proper string, then add support for lazy translation objects at the
end.</p>
</div>
</div>
</div>
<div class="section" id="s-id1">
<span id="s-how-to-create-language-files"></span><span id="id1"></span><span id="how-to-create-language-files"></span><h2>2. How to create language files<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>Once you've tagged your strings for later translation, you need to write (or
obtain) the language translations themselves. Here's how that works.</p>
<div class="admonition-locale-restrictions admonition">
<p class="first admonition-title">Locale restrictions</p>
<p class="last">Django does not support localizing your application into a locale for
which Django itself has not been translated. In this case, it will ignore
your translation files. If you were to try this and Django supported it,
you would inevitably see a mixture of translated strings (from your
application) and English strings (from Django itself). If you want to
support a locale for your application that is not already part of
Django, you'll need to make at least a minimal translation of the Django
core. See the relevant <a class="reference internal" href="#locale-middleware-notes"><em>LocaleMiddleware note</em></a>
for more details.</p>
</div>
<div class="section" id="s-message-files">
<span id="message-files"></span><h3>Message files<a class="headerlink" href="#message-files" title="Permalink to this headline">¶</a></h3>
<p>The first step is to create a <strong>message file</strong> for a new language. A message
file is a plain-text file, representing a single language, that contains all
available translation strings and how they should be represented in the given
language. Message files have a <tt class="docutils literal"><span class="pre">.po</span></tt> file extension.</p>
<p>Django comes with a tool, <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt>, that automates the
creation and upkeep of these files.</p>
<div class="admonition-a-note-to-django-veterans admonition">
<p class="first admonition-title">A note to Django veterans</p>
<p class="last">The old tool <tt class="docutils literal"><span class="pre">bin/make-messages.py</span></tt> has been moved to the command
<tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt> to provide consistency throughout Django.</p>
</div>
<p>To create or update a message file, run this command:</p>
<div class="highlight-python"><pre>django-admin.py makemessages -l de</pre>
</div>
<p>...where <tt class="docutils literal"><span class="pre">de</span></tt> is the language code for the message file you want to create.
The language code, in this case, is in locale format. For example, it's
<tt class="docutils literal"><span class="pre">pt_BR</span></tt> for Brazilian Portuguese and <tt class="docutils literal"><span class="pre">de_AT</span></tt> for Austrian German.</p>
<p>The script should be run from one of three places:</p>
<ul class="simple">
<li>The root directory of your Django project.</li>
<li>The root directory of your Django app.</li>
<li>The root <tt class="docutils literal"><span class="pre">django</span></tt> directory (not a Subversion checkout, but the one
that is linked-to via <tt class="docutils literal"><span class="pre">$PYTHONPATH</span></tt> or is located somewhere on that
path). This is only relevant when you are creating a translation for
Django itself, see <a class="reference external" href="http://docs.djangoproject.com/en/1.0/internals/contributing/#contributing-translations"><em>Submitting and maintaining translations</em></a>.</li>
</ul>
<p>The script runs over your project source tree or your application source tree
and pulls out all strings marked for translation. It creates (or updates) a
message file in the directory <tt class="docutils literal"><span class="pre">locale/LANG/LC_MESSAGES</span></tt>. In the <tt class="docutils literal"><span class="pre">de</span></tt>
example, the file will be <tt class="docutils literal"><span class="pre">locale/de/LC_MESSAGES/django.po</span></tt>.</p>
<p>By default <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt> examines every file that has the
<tt class="docutils literal"><span class="pre">.html</span></tt> file extension. In case you want to override that default, use the
<tt class="docutils literal"><span class="pre">--extension</span></tt> or <tt class="docutils literal"><span class="pre">-e</span></tt> option to specify the file extensions to examine:</p>
<div class="highlight-python"><pre>django-admin.py makemessages -l de -e txt</pre>
</div>
<p>Separate multiple extensions with commas and/or use <tt class="docutils literal"><span class="pre">-e</span></tt> or <tt class="docutils literal"><span class="pre">--extension</span></tt>
multiple times:</p>
<div class="highlight-python"><pre>django-admin.py makemessages -l=de -e=html,txt -e xml</pre>
</div>
<p>When <a class="reference internal" href="#creating-javascript-translation-catalogs">creating JavaScript translation catalogs</a> you need to use the special
'djangojs' domain, <strong>not</strong> <tt class="docutils literal"><span class="pre">-e</span> <span class="pre">js</span></tt>.</p>
<div class="admonition-no-gettext admonition">
<p class="first admonition-title">No gettext?</p>
<p class="last">If you don't have the <tt class="docutils literal"><span class="pre">gettext</span></tt> utilities installed, <tt class="docutils literal"><span class="pre">django-admin.py</span>
<span class="pre">makemessages</span></tt> will create empty files. If that's the case, either install
the <tt class="docutils literal"><span class="pre">gettext</span></tt> utilities or just copy the English message file
(<tt class="docutils literal"><span class="pre">locale/en/LC_MESSAGES/django.po</span></tt>) if available and use it as a starting
point; it's just an empty translation file.</p>
</div>
<div class="admonition-working-on-windows admonition">
<p class="first admonition-title">Working on Windows?</p>
<p class="last">If you're using Windows and need to install the GNU gettext utilities so
<tt class="docutils literal"><span class="pre">django-admin</span> <span class="pre">makemessages</span></tt> works see <a class="reference internal" href="#gettext-on-windows">gettext on Windows</a> for more
information.</p>
</div>
<p>The format of <tt class="docutils literal"><span class="pre">.po</span></tt> files is straightforward. Each <tt class="docutils literal"><span class="pre">.po</span></tt> file contains a
small bit of metadata, such as the translation maintainer's contact
information, but the bulk of the file is a list of <strong>messages</strong> -- simple
mappings between translation strings and the actual translated text for the
particular language.</p>
<p>For example, if your Django app contained a translation string for the text
<tt class="docutils literal"><span class="pre">"Welcome</span> <span class="pre">to</span> <span class="pre">my</span> <span class="pre">site."</span></tt>, like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">_</span><span class="p">(</span><span class="s">"Welcome to my site."</span><span class="p">)</span>
</pre></div>
</div>
<p>...then <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt> will have created a <tt class="docutils literal"><span class="pre">.po</span></tt> file
containing the following snippet -- a message:</p>
<div class="highlight-python"><pre>#: path/to/python/module.py:23
msgid "Welcome to my site."
msgstr ""</pre>
</div>
<p>A quick explanation:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">msgid</span></tt> is the translation string, which appears in the source. Don't
change it.</li>
<li><tt class="docutils literal"><span class="pre">msgstr</span></tt> is where you put the language-specific translation. It starts
out empty, so it's your responsibility to change it. Make sure you keep
the quotes around your translation.</li>
<li>As a convenience, each message includes, in the form of a comment line
prefixed with <tt class="docutils literal"><span class="pre">#</span></tt> and located above the <tt class="docutils literal"><span class="pre">msgid</span></tt> line, the filename and
line number from which the translation string was gleaned.</li>
</ul>
<p>Long messages are a special case. There, the first string directly after the
<tt class="docutils literal"><span class="pre">msgstr</span></tt> (or <tt class="docutils literal"><span class="pre">msgid</span></tt>) is an empty string. Then the content itself will be
written over the next few lines as one string per line. Those strings are
directly concatenated. Don't forget trailing spaces within the strings;
otherwise, they'll be tacked together without whitespace!</p>
<div class="admonition-mind-your-charset admonition">
<p class="first admonition-title">Mind your charset</p>
<p class="last">When creating a PO file with your favorite text editor, first edit
the charset line (search for <tt class="docutils literal"><span class="pre">"CHARSET"</span></tt>) and set it to the charset
you'll be using to edit the content. Due to the way the <tt class="docutils literal"><span class="pre">gettext</span></tt> tools
work internally and because we want to allow non-ASCII source strings in
Django's core and your applications, you <strong>must</strong> use UTF-8 as the encoding
for your PO file. This means that everybody will be using the same
encoding, which is important when Django processes the PO files.</p>
</div>
<p>To reexamine all source code and templates for new translation strings and
update all message files for <strong>all</strong> languages, run this:</p>
<div class="highlight-python"><pre>django-admin.py makemessages -a</pre>
</div>
</div>
<div class="section" id="s-compiling-message-files">
<span id="compiling-message-files"></span><h3>Compiling message files<a class="headerlink" href="#compiling-message-files" title="Permalink to this headline">¶</a></h3>
<p>After you create your message file -- and each time you make changes to it --
you'll need to compile it into a more efficient form, for use by <tt class="docutils literal"><span class="pre">gettext</span></tt>.
Do this with the <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span></tt> utility.</p>
<p>This tool runs over all available <tt class="docutils literal"><span class="pre">.po</span></tt> files and creates <tt class="docutils literal"><span class="pre">.mo</span></tt> files, which
are binary files optimized for use by <tt class="docutils literal"><span class="pre">gettext</span></tt>. In the same directory from
which you ran <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt>, run <tt class="docutils literal"><span class="pre">django-admin.py</span>
<span class="pre">compilemessages</span></tt> like this:</p>
<div class="highlight-python"><pre>django-admin.py compilemessages</pre>
</div>
<p>That's it. Your translations are ready for use.</p>
<div class="admonition-a-note-to-django-veterans admonition">
<p class="first admonition-title">A note to Django veterans</p>
<p class="last">The old tool <tt class="docutils literal"><span class="pre">bin/compile-messages.py</span></tt> has been moved to the command
<tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span></tt> to provide consistency throughout
Django.</p>
</div>
<div class="admonition-working-on-windows admonition">
<p class="first admonition-title">Working on Windows?</p>
<p class="last">If you're using Windows and need to install the GNU gettext utilities so
<tt class="docutils literal"><span class="pre">django-admin</span> <span class="pre">compilemessages</span></tt> works see <a class="reference internal" href="#gettext-on-windows">gettext on Windows</a> for more
information.</p>
</div>
</div>
</div>
<div class="section" id="s-id2">
<span id="s-how-django-discovers-language-preference"></span><span id="id2"></span><span id="how-django-discovers-language-preference"></span><h2>3. How Django discovers language preference<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h2>
<p>Once you've prepared your translations -- or, if you just want to use the
translations that come with Django -- you'll just need to activate translation
for your app.</p>
<p>Behind the scenes, Django has a very flexible model of deciding which language
should be used -- installation-wide, for a particular user, or both.</p>
<p>To set an installation-wide language preference, set <a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/settings/#setting-LANGUAGE_CODE"><tt class="xref docutils literal"><span class="pre">LANGUAGE_CODE</span></tt></a>.
Django uses this language as the default translation -- the final attempt if no
other translator finds a translation.</p>
<p>If all you want to do is run Django with your native language, and a language
file is available for your language, all you need to do is set
<tt class="docutils literal"><span class="pre">LANGUAGE_CODE</span></tt>.</p>
<p>If you want to let each individual user specify which language he or she
prefers, use <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt>. <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt> enables language
selection based on data from the request. It customizes content for each user.</p>
<p>To use <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt>, add <tt class="docutils literal"><span class="pre">'django.middleware.locale.LocaleMiddleware'</span></tt>
to your <tt class="docutils literal"><span class="pre">MIDDLEWARE_CLASSES</span></tt> setting. Because middleware order matters, you
should follow these guidelines:</p>
<ul class="simple">
<li>Make sure it's one of the first middlewares installed.</li>
<li>It should come after <tt class="docutils literal"><span class="pre">SessionMiddleware</span></tt>, because <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt>
makes use of session data.</li>
<li>If you use <tt class="docutils literal"><span class="pre">CacheMiddleware</span></tt>, put <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt> after it.</li>
</ul>
<p>For example, your <tt class="docutils literal"><span class="pre">MIDDLEWARE_CLASSES</span></tt> might look like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">MIDDLEWARE_CLASSES</span> <span class="o">=</span> <span class="p">(</span>
   <span class="s">'django.contrib.sessions.middleware.SessionMiddleware'</span><span class="p">,</span>
   <span class="s">'django.middleware.locale.LocaleMiddleware'</span><span class="p">,</span>
   <span class="s">'django.middleware.common.CommonMiddleware'</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>(For more on middleware, see the <a class="reference external" href="http://docs.djangoproject.com/en/1.0/topics/http/middleware/#topics-http-middleware"><em>middleware documentation</em></a>.)</p>
<p><tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt> tries to determine the user's language preference by
following this algorithm:</p>
<ul>
<li><p class="first">First, it looks for a <tt class="docutils literal"><span class="pre">django_language</span></tt> key in the current user's
session.</p>
</li>
<li><p class="first">Failing that, it looks for a cookie.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.0:</span> <a class="reference external" href="http://docs.djangoproject.com/en/1.0/releases/1.0/#releases-1-0"><em>Please, see the release notes</em></a></div>
<p>In Django version 0.96 and before, the cookie's name is hard-coded to
<tt class="docutils literal"><span class="pre">django_language</span></tt>. In Django 1,0, The cookie name is set by the
<tt class="docutils literal"><span class="pre">LANGUAGE_COOKIE_NAME</span></tt> setting. (The default name is
<tt class="docutils literal"><span class="pre">django_language</span></tt>.)</p>
</li>
<li><p class="first">Failing that, it looks at the <tt class="docutils literal"><span class="pre">Accept-Language</span></tt> HTTP header. This
header is sent by your browser and tells the server which language(s) you
prefer, in order by priority. Django tries each language in the header
until it finds one with available translations.</p>
</li>
<li><p class="first">Failing that, it uses the global <tt class="docutils literal"><span class="pre">LANGUAGE_CODE</span></tt> setting.</p>
</li>
</ul>
<p id="locale-middleware-notes">Notes:</p>
<ul>
<li><p class="first">In each of these places, the language preference is expected to be in the
standard language format, as a string. For example, Brazilian Portuguese
is <tt class="docutils literal"><span class="pre">pt-br</span></tt>.</p>
</li>
<li><p class="first">If a base language is available but the sublanguage specified is not,
Django uses the base language. For example, if a user specifies <tt class="docutils literal"><span class="pre">de-at</span></tt>
(Austrian German) but Django only has <tt class="docutils literal"><span class="pre">de</span></tt> available, Django uses
<tt class="docutils literal"><span class="pre">de</span></tt>.</p>
</li>
<li><p class="first">Only languages listed in the <a class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/settings/#setting-LANGUAGES"><tt class="xref docutils literal"><span class="pre">LANGUAGES</span></tt></a> setting can be selected.
If you want to restrict the language selection to a subset of provided
languages (because your application doesn't provide all those languages),
set <tt class="docutils literal"><span class="pre">LANGUAGES</span></tt> to a list of languages. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">LANGUAGES</span> <span class="o">=</span> <span class="p">(</span>
  <span class="p">(</span><span class="s">'de'</span><span class="p">,</span> <span class="n">_</span><span class="p">(</span><span class="s">'German'</span><span class="p">)),</span>
  <span class="p">(</span><span class="s">'en'</span><span class="p">,</span> <span class="n">_</span><span class="p">(</span><span class="s">'English'</span><span class="p">)),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This example restricts languages that are available for automatic
selection to German and English (and any sublanguage, like de-ch or
en-us).</p>
</li>
<li><p class="first">If you define a custom <tt class="docutils literal"><span class="pre">LANGUAGES</span></tt> setting, as explained in the
previous bullet, it's OK to mark the languages as translation strings
-- but use a "dummy" <tt class="docutils literal"><span class="pre">ugettext()</span></tt> function, not the one in
<tt class="docutils literal"><span class="pre">django.utils.translation</span></tt>. You should <em>never</em> import
<tt class="docutils literal"><span class="pre">django.utils.translation</span></tt> from within your settings file, because that
module in itself depends on the settings, and that would cause a circular
import.</p>
<p>The solution is to use a "dummy" <tt class="docutils literal"><span class="pre">ugettext()</span></tt> function. Here's a sample
settings file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">ugettext</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">s</span><span class="p">:</span> <span class="n">s</span>

<span class="n">LANGUAGES</span> <span class="o">=</span> <span class="p">(</span>
    <span class="p">(</span><span class="s">'de'</span><span class="p">,</span> <span class="n">ugettext</span><span class="p">(</span><span class="s">'German'</span><span class="p">)),</span>
    <span class="p">(</span><span class="s">'en'</span><span class="p">,</span> <span class="n">ugettext</span><span class="p">(</span><span class="s">'English'</span><span class="p">)),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>With this arrangement, <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt> will still find
and mark these strings for translation, but the translation won't happen
at runtime -- so you'll have to remember to wrap the languages in the
<em>real</em> <tt class="docutils literal"><span class="pre">ugettext()</span></tt> in any code that uses <tt class="docutils literal"><span class="pre">LANGUAGES</span></tt> at runtime.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt> can only select languages for which there is a
Django-provided base translation. If you want to provide translations
for your application that aren't already in the set of translations
in Django's source tree, you'll want to provide at least basic
translations for that language. For example, Django uses technical
message IDs to translate date formats and time formats -- so you will
need at least those translations for the system to work correctly.</p>
<p>A good starting point is to copy the English <tt class="docutils literal"><span class="pre">.po</span></tt> file and to
translate at least the technical messages -- maybe the validation
messages, too.</p>
<p>Technical message IDs are easily recognized; they're all upper case. You
don't translate the message ID as with other messages, you provide the
correct local variant on the provided English value. For example, with
<tt class="docutils literal"><span class="pre">DATETIME_FORMAT</span></tt> (or <tt class="docutils literal"><span class="pre">DATE_FORMAT</span></tt> or <tt class="docutils literal"><span class="pre">TIME_FORMAT</span></tt>), this would
be the format string that you want to use in your language. The format
is identical to the format strings used by the <tt class="docutils literal"><span class="pre">now</span></tt> template tag.</p>
</li>
</ul>
<p>Once <tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt> determines the user's preference, it makes this
preference available as <tt class="docutils literal"><span class="pre">request.LANGUAGE_CODE</span></tt> for each
<a title="django.http.HttpRequest" class="reference external" href="http://docs.djangoproject.com/en/1.0/ref/request-response/#django.http.HttpRequest"><tt class="xref docutils literal"><span class="pre">HttpRequest</span></tt></a>. Feel free to read this value in your view
code. Here's a simple example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">hello_world</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">count</span><span class="p">):</span>
    <span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">LANGUAGE_CODE</span> <span class="o">==</span> <span class="s">'de-at'</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s">"You prefer to read Austrian German."</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="s">"You prefer to read another language."</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that, with static (middleware-less) translation, the language is in
<tt class="docutils literal"><span class="pre">settings.LANGUAGE_CODE</span></tt>, while with dynamic (middleware) translation, it's
in <tt class="docutils literal"><span class="pre">request.LANGUAGE_CODE</span></tt>.</p>
</div>
<div class="section" id="s-using-translations-in-your-own-projects">
<span id="s-translations-in-your-own-projects"></span><span id="using-translations-in-your-own-projects"></span><span id="translations-in-your-own-projects"></span><h2>Using translations in your own projects<a class="headerlink" href="#using-translations-in-your-own-projects" title="Permalink to this headline">¶</a></h2>
<p>Django looks for translations by following this algorithm:</p>
<ul class="simple">
<li>First, it looks for a <tt class="docutils literal"><span class="pre">locale</span></tt> directory in the application directory
of the view that's being called. If it finds a translation for the
selected language, the translation will be installed.</li>
<li>Next, it looks for a <tt class="docutils literal"><span class="pre">locale</span></tt> directory in the project directory. If it
finds a translation, the translation will be installed.</li>
<li>Finally, it checks the Django-provided base translation in
<tt class="docutils literal"><span class="pre">django/conf/locale</span></tt>.</li>
</ul>
<p>This way, you can write applications that include their own translations, and
you can override base translations in your project path. Or, you can just build
a big project out of several apps and put all translations into one big project
message file. The choice is yours.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you're using manually configured settings, as described
<a class="reference external" href="http://docs.djangoproject.com/en/1.0/topics/settings/#settings-without-django-settings-module"><em>Using settings without setting DJANGO_SETTINGS_MODULE</em></a>, the <tt class="docutils literal"><span class="pre">locale</span></tt> directory in
the project directory will not be examined, since Django loses the ability
to work out the location of the project directory. (Django normally uses the
location of the settings file to determine this, and a settings file doesn't
exist if you're manually configuring your settings.)</p>
</div>
<p>All message file repositories are structured the same way. They are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">$APPPATH/locale/&lt;language&gt;/LC_MESSAGES/django.(po|mo)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">$PROJECTPATH/locale/&lt;language&gt;/LC_MESSAGES/django.(po|mo)</span></tt></li>
<li>All paths listed in <tt class="docutils literal"><span class="pre">LOCALE_PATHS</span></tt> in your settings file are
searched in that order for <tt class="docutils literal"><span class="pre">&lt;language&gt;/LC_MESSAGES/django.(po|mo)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">$PYTHONPATH/django/conf/locale/&lt;language&gt;/LC_MESSAGES/django.(po|mo)</span></tt></li>
</ul>
<p>To create message files, you use the same <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt>
tool as with the Django message files. You only need to be in the right place
-- in the directory where either the <tt class="docutils literal"><span class="pre">conf/locale</span></tt> (in case of the source
tree) or the <tt class="docutils literal"><span class="pre">locale/</span></tt> (in case of app messages or project messages)
directory are located. And you use the same <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span></tt>
to produce the binary <tt class="docutils literal"><span class="pre">django.mo</span></tt> files that are used by <tt class="docutils literal"><span class="pre">gettext</span></tt>.</p>
<p>You can also run <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span> <span class="pre">--settings=path.to.settings</span></tt>
to make the compiler process all the directories in your <tt class="docutils literal"><span class="pre">LOCALE_PATHS</span></tt>
setting.</p>
<p>Application message files are a bit complicated to discover -- they need the
<tt class="docutils literal"><span class="pre">LocaleMiddleware</span></tt>. If you don't use the middleware, only the Django message
files and project message files will be processed.</p>
<p>Finally, you should give some thought to the structure of your translation
files. If your applications need to be delivered to other users and will
be used in other projects, you might want to use app-specific translations.
But using app-specific translations and project translations could produce
weird problems with <tt class="docutils literal"><span class="pre">makemessages</span></tt>: <tt class="docutils literal"><span class="pre">makemessages</span></tt> will traverse all
directories below the current path and so might put message IDs into the
project message file that are already in application message files.</p>
<p>The easiest way out is to store applications that are not part of the project
(and so carry their own translations) outside the project tree. That way,
<tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt> on the project level will only translate
strings that are connected to your explicit project and not strings that are
distributed independently.</p>
</div>
<div class="section" id="s-the-set-language-redirect-view">
<span id="the-set-language-redirect-view"></span><h2>The <tt class="docutils literal"><span class="pre">set_language</span></tt> redirect view<a class="headerlink" href="#the-set-language-redirect-view" title="Permalink to this headline">¶</a></h2>
<p>As a convenience, Django comes with a view, <tt class="docutils literal"><span class="pre">django.views.i18n.set_language</span></tt>,
that sets a user's language preference and redirects back to the previous page.</p>
<p>Activate this view by adding the following line to your URLconf:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">(</span><span class="s">r'^i18n/'</span><span class="p">,</span> <span class="n">include</span><span class="p">(</span><span class="s">'django.conf.urls.i18n'</span><span class="p">)),</span>
</pre></div>
</div>
<p>(Note that this example makes the view available at <tt class="docutils literal"><span class="pre">/i18n/setlang/</span></tt>.)</p>
<p>The view expects to be called via the <tt class="docutils literal"><span class="pre">POST</span></tt> method, with a <tt class="docutils literal"><span class="pre">language</span></tt>
parameter set in request. If session support is enabled, the view
saves the language choice in the user's session. Otherwise, it saves the
language choice in a cookie that is by default named <tt class="docutils literal"><span class="pre">django_language</span></tt>.
(The name can be changed through the <tt class="docutils literal"><span class="pre">LANGUAGE_COOKIE_NAME</span></tt> setting.)</p>
<p>After setting the language choice, Django redirects the user, following this
algorithm:</p>
<ul class="simple">
<li>Django looks for a <tt class="docutils literal"><span class="pre">next</span></tt> parameter in the <tt class="docutils literal"><span class="pre">POST</span></tt> data.</li>
<li>If that doesn't exist, or is empty, Django tries the URL in the
<tt class="docutils literal"><span class="pre">Referrer</span></tt> header.</li>
<li>If that's empty -- say, if a user's browser suppresses that header --
then the user will be redirected to <tt class="docutils literal"><span class="pre">/</span></tt> (the site root) as a fallback.</li>
</ul>
<p>Here's example HTML template code:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="nt">&lt;form</span> <span class="na">action=</span><span class="s">"/i18n/setlang/"</span> <span class="na">method=</span><span class="s">"post"</span><span class="nt">&gt;</span>
<span class="nt">&lt;input</span> <span class="na">name=</span><span class="s">"next"</span> <span class="na">type=</span><span class="s">"hidden"</span> <span class="na">value=</span><span class="s">"/next/page/"</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;select</span> <span class="na">name=</span><span class="s">"language"</span><span class="nt">&gt;</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">lang</span> <span class="k">in</span> <span class="nv">LANGUAGES</span> <span class="cp">%}</span>
<span class="nt">&lt;option</span> <span class="na">value=</span><span class="s">"</span><span class="cp">{{</span> <span class="nv">lang.0</span> <span class="cp">}}</span><span class="s">"</span><span class="nt">&gt;</span><span class="cp">{{</span> <span class="nv">lang.1</span> <span class="cp">}}</span><span class="nt">&lt;/option&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="nt">&lt;/select&gt;</span>
<span class="nt">&lt;input</span> <span class="na">type=</span><span class="s">"submit"</span> <span class="na">value=</span><span class="s">"Go"</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/form&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-translations-and-javascript">
<span id="translations-and-javascript"></span><h2>Translations and JavaScript<a class="headerlink" href="#translations-and-javascript" title="Permalink to this headline">¶</a></h2>
<p>Adding translations to JavaScript poses some problems:</p>
<ul class="simple">
<li>JavaScript code doesn't have access to a <tt class="docutils literal"><span class="pre">gettext</span></tt> implementation.</li>
<li>JavaScript code doesn't have access to .po or .mo files; they need to be
delivered by the server.</li>
<li>The translation catalogs for JavaScript should be kept as small as
possible.</li>
</ul>
<p>Django provides an integrated solution for these problems: It passes the
translations into JavaScript, so you can call <tt class="docutils literal"><span class="pre">gettext</span></tt>, etc., from within
JavaScript.</p>
<div class="section" id="s-the-javascript-catalog-view">
<span id="the-javascript-catalog-view"></span><h3>The <tt class="docutils literal"><span class="pre">javascript_catalog</span></tt> view<a class="headerlink" href="#the-javascript-catalog-view" title="Permalink to this headline">¶</a></h3>
<p>The main solution to these problems is the <tt class="docutils literal"><span class="pre">javascript_catalog</span></tt> view, which
sends out a JavaScript code library with functions that mimic the <tt class="docutils literal"><span class="pre">gettext</span></tt>
interface, plus an array of translation strings. Those translation strings are
taken from the application, project or Django core, according to what you
specify in either the info_dict or the URL.</p>
<p>You hook it up like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">js_info_dict</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s">'packages'</span><span class="p">:</span> <span class="p">(</span><span class="s">'your.app.package'</span><span class="p">,),</span>
<span class="p">}</span>

<span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
    <span class="p">(</span><span class="s">r'^jsi18n/$'</span><span class="p">,</span> <span class="s">'django.views.i18n.javascript_catalog'</span><span class="p">,</span> <span class="n">js_info_dict</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Each string in <tt class="docutils literal"><span class="pre">packages</span></tt> should be in Python dotted-package syntax (the
same format as the strings in <tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt>) and should refer to a package
that contains a <tt class="docutils literal"><span class="pre">locale</span></tt> directory. If you specify multiple packages, all
those catalogs are merged into one catalog. This is useful if you have
JavaScript that uses strings from different applications.</p>
<p>You can make the view dynamic by putting the packages into the URL pattern:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">urlpatterns</span> <span class="o">=</span> <span class="n">patterns</span><span class="p">(</span><span class="s">''</span><span class="p">,</span>
    <span class="p">(</span><span class="s">r'^jsi18n/(?P&lt;packages&gt;\S+?)/$'</span><span class="p">,</span> <span class="s">'django.views.i18n.javascript_catalog'</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>With this, you specify the packages as a list of package names delimited by '+'
signs in the URL. This is especially useful if your pages use code from
different apps and this changes often and you don't want to pull in one big
catalog file. As a security measure, these values can only be either
<tt class="docutils literal"><span class="pre">django.conf</span></tt> or any package from the <tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt> setting.</p>
</div>
<div class="section" id="s-using-the-javascript-translation-catalog">
<span id="using-the-javascript-translation-catalog"></span><h3>Using the JavaScript translation catalog<a class="headerlink" href="#using-the-javascript-translation-catalog" title="Permalink to this headline">¶</a></h3>
<p>To use the catalog, just pull in the dynamically generated script like this:</p>
<div class="highlight-python"><pre>&lt;script type="text/javascript" src="/path/to/jsi18n/"&gt;&lt;/script&gt;</pre>
</div>
<p>This is how the admin fetches the translation catalog from the server. When the
catalog is loaded, your JavaScript code can use the standard <tt class="docutils literal"><span class="pre">gettext</span></tt>
interface to access it:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">document</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">gettext</span><span class="p">(</span><span class="s">'this is to be translated'</span><span class="p">));</span>
</pre></div>
</div>
<p>There is also an <tt class="docutils literal"><span class="pre">ngettext</span></tt> interface:</p>
<div class="highlight-python"><pre>var object_cnt = 1 // or 0, or 2, or 3, ...
s = ngettext('literal for the singular case',
        'literal for the plural case', object_cnt);</pre>
</div>
<p>and even a string interpolation function:</p>
<div class="highlight-python"><pre>function interpolate(fmt, obj, named);</pre>
</div>
<p>The interpolation syntax is borrowed from Python, so the <tt class="docutils literal"><span class="pre">interpolate</span></tt>
function supports both positional and named interpolation:</p>
<ul>
<li><p class="first">Positional interpolation: <tt class="docutils literal"><span class="pre">obj</span></tt> contains a JavaScript Array object
whose elements values are then sequentially interpolated in their
corresponding <tt class="docutils literal"><span class="pre">fmt</span></tt> placeholders in the same order they appear.
For example:</p>
<div class="highlight-python"><pre>fmts = ngettext('There is %s object. Remaining: %s',
        'There are %s objects. Remaining: %s', 11);
s = interpolate(fmts, [11, 20]);
// s is 'There are 11 objects. Remaining: 20'</pre>
</div>
</li>
<li><p class="first">Named interpolation: This mode is selected by passing the optional
boolean <tt class="docutils literal"><span class="pre">named</span></tt> parameter as true. <tt class="docutils literal"><span class="pre">obj</span></tt> contains a JavaScript
object or associative array. For example:</p>
<div class="highlight-python"><pre>d = {
    count: 10
    total: 50
};

fmts = ngettext('Total: %(total)s, there is %(count)s object',
'there are %(count)s of a total of %(total)s objects', d.count);
s = interpolate(fmts, d, true);</pre>
</div>
</li>
</ul>
<p>You shouldn't go over the top with string interpolation, though: this is still
JavaScript, so the code has to make repeated regular-expression substitutions.
This isn't as fast as string interpolation in Python, so keep it to those
cases where you really need it (for example, in conjunction with <tt class="docutils literal"><span class="pre">ngettext</span></tt>
to produce proper pluralizations).</p>
</div>
<div class="section" id="s-creating-javascript-translation-catalogs">
<span id="creating-javascript-translation-catalogs"></span><h3>Creating JavaScript translation catalogs<a class="headerlink" href="#creating-javascript-translation-catalogs" title="Permalink to this headline">¶</a></h3>
<p>You create and update the translation catalogs the same way as the other</p>
<p>Django translation catalogs -- with the django-admin.py makemessages tool. The
only difference is you need to provide a <tt class="docutils literal"><span class="pre">-d</span> <span class="pre">djangojs</span></tt> parameter, like this:</p>
<div class="highlight-python"><pre>django-admin.py makemessages -d djangojs -l de</pre>
</div>
<p>This would create or update the translation catalog for JavaScript for German.
After updating translation catalogs, just run <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span></tt>
the same way as you do with normal Django translation catalogs.</p>
</div>
</div>
<div class="section" id="s-specialties-of-django-translation">
<span id="specialties-of-django-translation"></span><h2>Specialties of Django translation<a class="headerlink" href="#specialties-of-django-translation" title="Permalink to this headline">¶</a></h2>
<p>If you know <tt class="docutils literal"><span class="pre">gettext</span></tt>, you might note these specialties in the way Django
does translation:</p>
<ul class="simple">
<li>The string domain is <tt class="docutils literal"><span class="pre">django</span></tt> or <tt class="docutils literal"><span class="pre">djangojs</span></tt>. This string domain is
used to differentiate between different programs that store their data
in a common message-file library (usually <tt class="docutils literal"><span class="pre">/usr/share/locale/</span></tt>). The
<tt class="docutils literal"><span class="pre">django</span></tt> domain is used for python and template translation strings
and is loaded into the global translation catalogs. The <tt class="docutils literal"><span class="pre">djangojs</span></tt>
domain is only used for JavaScript translation catalogs to make sure
that those are as small as possible.</li>
<li>Django doesn't use <tt class="docutils literal"><span class="pre">xgettext</span></tt> alone. It uses Python wrappers around
<tt class="docutils literal"><span class="pre">xgettext</span></tt> and <tt class="docutils literal"><span class="pre">msgfmt</span></tt>. This is mostly for convenience.</li>
</ul>
</div>
<div class="section" id="s-gettext-on-windows">
<span id="gettext-on-windows"></span><h2><tt class="docutils literal"><span class="pre">gettext</span></tt> on Windows<a class="headerlink" href="#gettext-on-windows" title="Permalink to this headline">¶</a></h2>
<p>This is only needed for people who either want to extract message IDs or compile
message files (<tt class="docutils literal"><span class="pre">.po</span></tt>). Translation work itself just involves editing existing
files of this type, but if you want to create your own message files, or want to
test or compile a changed message file, you will need the <tt class="docutils literal"><span class="pre">gettext</span></tt> utilities:</p>
<ul class="simple">
<li>Download the following zip files from
<a class="reference external" href="http://sourceforge.net/projects/gettext">http://sourceforge.net/projects/gettext</a><ul>
<li><tt class="docutils literal"><span class="pre">gettext-runtime-X.bin.woe32.zip</span></tt></li>
<li><tt class="docutils literal"><span class="pre">gettext-tools-X.bin.woe32.zip</span></tt></li>
<li><tt class="docutils literal"><span class="pre">libiconv-X.bin.woe32.zip</span></tt></li>
</ul>
</li>
<li>Extract the 3 files in the same folder (i.e. <tt class="docutils literal"><span class="pre">C:\Program</span>
<span class="pre">Files\gettext-utils</span></tt>)</li>
<li>Update the system PATH:<ul>
<li><tt class="docutils literal"><span class="pre">Control</span> <span class="pre">Panel</span> <span class="pre">&gt;</span> <span class="pre">System</span> <span class="pre">&gt;</span> <span class="pre">Advanced</span> <span class="pre">&gt;</span> <span class="pre">Environment</span> <span class="pre">Variables</span></tt></li>
<li>In the <tt class="docutils literal"><span class="pre">System</span> <span class="pre">variables</span></tt> list, click <tt class="docutils literal"><span class="pre">Path</span></tt>, click <tt class="docutils literal"><span class="pre">Edit</span></tt></li>
<li>Add <tt class="docutils literal"><span class="pre">;C:\Program</span> <span class="pre">Files\gettext-utils\bin</span></tt> at the end of the
<tt class="docutils literal"><span class="pre">Variable</span> <span class="pre">value</span></tt> field</li>
</ul>
</li>
</ul>
<p>You may also use <tt class="docutils literal"><span class="pre">gettext</span></tt> binaries you have obtained elsewhere, so long as
the <tt class="docutils literal"><span class="pre">xgettext</span> <span class="pre">--version</span></tt> command works properly. Some version 0.14.4 binaries
have been found to not support this command. Do not attempt to use Django
translation utilities with a <tt class="docutils literal"><span class="pre">gettext</span></tt> package if the command <tt class="docutils literal"><span class="pre">xgettext</span>
<span class="pre">--version</span></tt> entered at a Windows command prompt causes a popup window saying
"xgettext.exe has generated errors and will be closed by Windows".</p>
</div>
</div>



<div id="content-secondary">
  <h2 id="comments">Questions/Feedback</h2>
  <p>Having trouble? We'd like to help!</p>
  <ul>
    <li>
      Try the <a href="http://docs.djangoproject.com/en/dev/faq/">FAQ</a> — it's got answers to many common
      questions.
    </li>
    <li>
      Search for information in the <a href="http://groups.google.com/group/django-users/">archives of the
      django-users mailing list</a>, or <a href="http://groups.google.com/group/django-users/">post a question</a>.
    </li>
    <li>
      Ask a question in the <a href="irc://irc.freenode.net/">#django IRC
      channel</a>, or search the <a href="http://oebfare.com/logger/django/">IRC
      logs</a> to see if its been asked before.
    </li>
    <li>
      If you notice errors with this documentation, please <a href="http://code.djangoproject.com/simpleticket?component=Documentation">
      open a ticket</a> and let us know! Please only use the ticket tracker for
      criticisms and improvements on the docs. For tech support, use the
      resources above.
    </li>
  </ul>
</div>

		</div>
		<!-- END #content-main -->
		<div id="content-related" class="sidebar">
		
  
    <h2>Contents</h2>
    
      <ul>
<li><a class="reference external" href="">Internationalization</a><ul>
<li><a class="reference external" href="#overview">Overview</a></li>
<li><a class="reference external" href="#if-you-don-t-need-internationalization-in-your-app">If you don’t need internationalization in your app</a></li>
<li><a class="reference external" href="#if-you-do-need-internationalization-three-steps">If you do need internationalization: three steps</a></li>
<li><a class="reference external" href="#how-to-specify-translation-strings">1. How to specify translation strings</a><ul>
<li><a class="reference external" href="#in-python-code">In Python code</a><ul>
<li><a class="reference external" href="#standard-translation">Standard translation</a></li>
<li><a class="reference external" href="#marking-strings-as-no-op">Marking strings as no-op</a></li>
<li><a class="reference external" href="#lazy-translation">Lazy translation</a></li>
<li><a class="reference external" href="#pluralization">Pluralization</a></li>
</ul>
</li>
<li><a class="reference external" href="#in-template-code">In template code</a></li>
<li><a class="reference external" href="#working-with-lazy-translation-objects">Working with lazy translation objects</a><ul>
<li><a class="reference external" href="#joining-strings-string-concat">Joining strings: string_concat()</a></li>
<li><a class="reference external" href="#the-allow-lazy-decorator">The allow_lazy() decorator</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference external" href="#id1">2. How to create language files</a><ul>
<li><a class="reference external" href="#message-files">Message files</a></li>
<li><a class="reference external" href="#compiling-message-files">Compiling message files</a></li>
</ul>
</li>
<li><a class="reference external" href="#id2">3. How Django discovers language preference</a></li>
<li><a class="reference external" href="#using-translations-in-your-own-projects">Using translations in your own projects</a></li>
<li><a class="reference external" href="#the-set-language-redirect-view">The <tt class="docutils literal"><span class="pre">set_language</span></tt> redirect view</a></li>
<li><a class="reference external" href="#translations-and-javascript">Translations and JavaScript</a><ul>
<li><a class="reference external" href="#the-javascript-catalog-view">The <tt class="docutils literal"><span class="pre">javascript_catalog</span></tt> view</a></li>
<li><a class="reference external" href="#using-the-javascript-translation-catalog">Using the JavaScript translation catalog</a></li>
<li><a class="reference external" href="#creating-javascript-translation-catalogs">Creating JavaScript translation catalogs</a></li>
</ul>
</li>
<li><a class="reference external" href="#specialties-of-django-translation">Specialties of Django translation</a></li>
<li><a class="reference external" href="#gettext-on-windows"><tt class="docutils literal"><span class="pre">gettext</span></tt> on Windows</a></li>
</ul>
</li>
</ul>

    
  
  
  
    <h2>Search</h2>
    
    <form action="/en/1.0/search/" id="search" class="search">
  <div>
    <input name="cx" value="009763561546736975936:e88ek0eurf4" type="hidden">
    <input name="cof" value="FORID:11" type="hidden">
    <input name="ie" value="UTF-8" type="hidden">
    <input name="hl" value="" type="hidden">
    <input style="background: rgb(255, 255, 255) url(http://www.google.com/coop/intl/en/images/google_custom_search_watermark.gif) no-repeat scroll left center; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" id="id_search_q" class="query" name="q" type="text">
    <input name="sa" class="submit" value="Search" type="submit">
    <ul>
<li><label for="id_search_as_q_0"><input checked="checked" id="id_search_as_q_0" value="more:dev_docs" name="as_q" type="radio"> Latest</label></li>
<li><label for="id_search_as_q_1"><input id="id_search_as_q_1" value="more:1.0_docs" name="as_q" type="radio"> 1.0</label></li>
<li><label for="id_search_as_q_2"><input id="id_search_as_q_2" value="more:0.96_docs" name="as_q" type="radio"> 0.96</label></li>
<li><label for="id_search_as_q_3"><input id="id_search_as_q_3" value="more:all_docs" name="as_q" type="radio"> All</label></li>
</ul>
  </div>
</form>
<script type="text/javascript" src="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/brand.html"></script>
  
  
  
    <h2>Browse</h2>
    <ul>
      
        
          <li>Prev: <a href="http://docs.djangoproject.com/en/1.0/topics/email/">Sending e-mail</a></li>
        
        
          <li>Next: <a href="http://docs.djangoproject.com/en/1.0/topics/pagination/">Pagination</a></li>
        
        <li><a href="http://docs.djangoproject.com/en/1.0/contents/">Table of contents</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/genindex/">General Index</a></li>
        
          <li><a href="http://docs.djangoproject.com/en/1.0/modindex/">Global Module Index</a></li>
        
      
    </ul>
  
  
  
    <h2>You are here:</h2>
    <ul>
      
        <li>
          <a href="http://docs.djangoproject.com/en/1.0/">Django 1.0 documentation</a>
          
            <ul><li><a href="http://docs.djangoproject.com/en/1.0/topics/">Using Django</a>
          
          <ul><li>Internationalization</li></ul>
          </li></ul>
        </li>
      
    </ul>
  
  
  
    <h3>Last update:</h3>
    <div>May 23, 2009, 8:15 a.m. (<a href="http://www.timeanddate.com/worldclock/city.html?n=64">CDT</a>)</div>
  

		</div>
		<!-- END #content-related -->

		</div>
		<!-- END #content -->
		<div id="footer">
			<p>© 2005-2009 <a href="http://www.djangoproject.com/foundation/">Django Software Foundation</a> unless otherwise noted. Django is a registered trademark of the Django Software Foundation. 
			Hosting graciously provided by <a href="http://mediatemple.net/">
			<img style="vertical-align: middle; position: relative; top: -1px;" src="Django%20%7C%20Internationalization%20%7C%20Django%20Documentation_files/mt.png" alt="media temple"></a>
			</p>
		</div>
		<!-- END #footer -->
	</div>
	<!-- END #container -->
	</body></html>